---
title: Annotations
icon: PencilLine
---

<MetaData
  lang="en-US"
  meta={{
    preset: [{
      client: '@univerjs/preset-sheets-note',
      locale: '@univerjs/preset-sheets-note/locales/en-US',
      style: '@univerjs/preset-sheets-note/lib/index.css',
    }],
    plugins: [{
      client: '@univerjs/sheets-note',
      facade: '@univerjs/sheets-note/facade',
    }, {
      client: '@univerjs/sheets-note-ui',
      locale: '@univerjs/sheets-note-ui/locale/en-US',
      style: '@univerjs/sheets-note-ui/lib/index.css',
    }],
    server: 'No',
  }}
/>

Annotations functionality allows users to add comments in spreadsheet cells to record additional information or provide context. It supports various comment styles and operations, helping users better understand and collaborate on data.

<PlaygroundFrame lang="en-US" slug="sheets/notes" clickToShow />

## Preset Mode

### Installation

```package-install
npm install @univerjs/preset-sheets-note
```

### Usage

```typescript
import { UniverSheetsCorePreset } from '@univerjs/preset-sheets-core'
import UniverPresetSheetsCoreEnUS from '@univerjs/preset-sheets-core/locales/en-US'
import { UniverSheetsNotePreset } from '@univerjs/preset-sheets-note' // [!code ++]
import UniverPresetSheetsNoteEnUS from '@univerjs/preset-sheets-note/locales/en-US' // [!code ++]
import { createUniver, LocaleType, mergeLocales } from '@univerjs/presets'

import '@univerjs/preset-sheets-core/lib/index.css'
import '@univerjs/preset-sheets-note/lib/index.css' // [!code ++]

const { univerAPI } = createUniver({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      UniverPresetSheetsCoreEnUS,
      UniverPresetSheetsNoteEnUS, // [!code ++]
    ),
  },
  presets: [
    UniverSheetsCorePreset(),
    UniverSheetsNotePreset(), // [!code ++]
  ],
})
```

{/* ### Presets and Configuration */}

## Plugin Mode

### Installation

```package-install
npm install @univerjs/sheets-note @univerjs/sheets-note-ui
```

### Usage

```typescript
import { LocaleType, mergeLocales, Univer } from '@univerjs/core'
import { UniverSheetsNotePlugin } from '@univerjs/sheets-note' // [!code ++]
import { UniverSheetsNoteUIPlugin } from '@univerjs/sheets-note-ui' // [!code ++]
import SheetsNoteUIEnUS from '@univerjs/sheets-note-ui/locale/en-US' // [!code ++]

import '@univerjs/sheets-note-ui/lib/index.css' // [!code ++]

import '@univerjs/sheets-note/facade' // [!code ++]

const univer = new Univer({
  locale: LocaleType.En_US,
  locales: {
    [LocaleType.En_US]: mergeLocales(
      SheetsNoteUIEnUS, // [!code ++]
    ),
  },
})

univer.registerPlugin(UniverSheetsNotePlugin) // [!code ++]
univer.registerPlugin(UniverSheetsNoteUIPlugin) // [!code ++]
```

{/* ### Plugins and Configuration */}

## Facade API

Complete Facade API type definitions can be found in the [FacadeAPI](https://reference.univer.ai/en-US).。

### Get Annotations

Using `FWorksheet.getNotes` to get all annotations in the worksheet.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const notes = fWorksheet.getNotes()

notes.forEach((item) => {
  const { row, col, note } = item
  console.log(`Cell ${fWorksheet.getRange(row, col).getA1Notation()} has note: ${note}`)
})
```

Using `FRange.getNote` to get the annotation of the top-left cell in the range.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1:D10')
const note = fRange.getNote()
```

### Add or Update Annotations

Using `FRange.createOrUpdateNote` to create or update the annotation of the top-left cell in the range.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const fRange = fWorksheet.getRange('A1')
fRange.createOrUpdateNote({
  note: 'This is an annotation',
  width: 160,
  height: 100,
  show: true,
})
```

### Remove Annotations

Using `FRange.deleteNote` to remove the annotation of the top-left cell in the range.

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const fWorksheet = fWorkbook.getActiveSheet()
const notes = fWorksheet.getNotes()

if (notes.length > 0) {
  // Remove the first annotation in the worksheet
  const { row, col } = notes[0]
  fWorksheet.getRange(row, col).deleteNote()
}

// Remove the annotation in cell C1
const fRange = fWorksheet.getRange('C1')
fRange.deleteNote()
```

### Event Listeners

Complete event type definitions can be found in the [Events](https://reference.univer.ai/en-US/classes/FEventName).

| Event Name | Description |
| ---------- | ----------- |
| `SheetNoteAdd` | Triggered after adding an annotation |
| `SheetNoteDelete` | Triggered after deleting an annotation |
| `SheetNoteUpdate` | Triggered after updating an annotation |
| `SheetNoteShow` | Triggered when an annotation is shown |
| `SheetNoteHide` | Triggered when an annotation is hidden |
| `BeforeSheetNoteAdd` | Triggered before adding an annotation |
| `BeforeSheetNoteDelete` | Triggered before deleting an annotation |
| `BeforeSheetNoteUpdate` | Triggered before updating an annotation |
| `BeforeSheetNoteShow` | Triggered before showing an annotation |
| `BeforeSheetNoteHide` | Triggered before hiding an annotation |

##### Event Listener Examples

```typescript
// Triggered after adding an annotation
const disposable = univerAPI.addEvent(univerAPI.Event.SheetNoteAdd, (params) => {
  const { workbook, worksheet, row, col, note } = params
})

// Remove event listener using `disposable.dispose()`
```

```typescript
// Triggered before removing an annotation, can be canceled
const disposable = univerAPI.addEvent(univerAPI.Event.BeforeSheetNoteDelete, (params) => {
  const { workbook, worksheet, row, col, oldNote } = params

  // Cancel the annotation deletion operation
  params.cancel = true
})

// Remove event listener using `disposable.dispose()`
```
